Skip to content

docs: document Stack Auth deployment setup#19

Merged
paccloud merged 1 commit into
mainfrom
issue-14-auth-docs
May 10, 2026
Merged

docs: document Stack Auth deployment setup#19
paccloud merged 1 commit into
mainfrom
issue-14-auth-docs

Conversation

@paccloud

@paccloud paccloud commented May 10, 2026

Copy link
Copy Markdown
Owner

Summary

  • add AUTH_ARCHITECTURE.md documenting the current JWT + Stack Auth + Neon architecture
  • add Stack Auth env vars, Trusted Domains setup, and Vercel integration cleanup to DEPLOYMENT.md
  • add troubleshooting for REDIRECT_URL_NOT_WHITELISTED and OAuth-only failures

Closes #14.

Verification

  • npm run build in app/ passed
  • npm run lint in app/ fails on existing React lint issues unrelated to this docs change, including unused vars and React hooks lint in existing source files
  • root npm test -- --runInBand could not run because the root package has no test script

@vercel

vercel Bot commented May 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
fish-cost-calculator Ready Ready Preview, Comment May 10, 2026 9:53pm

@coderabbitai

coderabbitai Bot commented May 10, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

Summary by CodeRabbit

  • Documentation
    • Added comprehensive authentication architecture documentation covering system design and migration options.
    • Updated deployment guide with enhanced setup instructions, environment configuration steps, and troubleshooting guidance for cloud platform deployment.

Walkthrough

This PR adds comprehensive documentation for the project's dual authentication system. A new AUTH_ARCHITECTURE.md file documents the current password/JWT and OAuth/Stack Auth flows, data persistence requirements keyed to users.id, future authentication requirements, operational considerations, and five migration options with a consolidation checklist. DEPLOYMENT.md is updated to include Stack Auth environment variables, a new post-deployment configuration step for Trusted Domains and integration cleanup, revised deployment verification procedures, and Stack Auth–specific troubleshooting for OAuth redirect and login failures.

Changes

Authentication Architecture and Deployment Documentation

Layer / File(s) Summary
Current Architecture
AUTH_ARCHITECTURE.md		 Introduces dual auth paths: password authentication (JWT + bcrypt) and OAuth (Stack Auth via Neon). Both map to the same users table via neon_auth_id and email.
Data Persistence & Migration Contract
AUTH_ARCHITECTURE.md		 User-owned data is keyed to users.id across tables. Future auth systems must support OAuth + email/password, cross-device identity persistence, req.user compatibility, and Neon/platform compatibility.
Operational Setup & Integration Management
AUTH_ARCHITECTURE.md, DEPLOYMENT.md		 Documents Stack Auth Trusted Domains requirements for OAuth redirects. Provides procedures to add production/preview domains, remove unused Clerk integration, and remove stale duplicate Neon integrations.
Migration Strategy & Checklist
AUTH_ARCHITECTURE.md		 Lists five auth options (Keep Stack Auth, Better Auth, Clerk, Auth.js, Supabase Auth) with trade-offs. Provides checklist for environment inventory, domain registration, integration cleanup, consolidation choice, mapping preservation, and end-to-end testing.
Deployment Environment Variables
DEPLOYMENT.md		 Updates Vercel env var table to include Stack Auth frontend/backend variables (VITE_STACK_PROJECT_ID, VITE_STACK_PUBLISHABLE_CLIENT_KEY, STACK_SECRET_SERVER_KEY).
Deployment Verification & Troubleshooting
DEPLOYMENT.md		 Restructures verification steps (Step 6 with new "Check API Logs" subsection). Adds Stack Auth–specific troubleshooting for REDIRECT_URL_NOT_WHITELISTED errors and OAuth-vs.-password login diagnosis.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

  • paccloud/Fish_Cost_Calculator#9: Earlier PR that also modifies Stack Auth environment variables and Vercel deployment configuration for the same Stack Auth + Neon integration.

Poem

🐰 Auth flows now charted,
Two paths through Neon bright,
JWT and OAuth danced,
Then docs made it right! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'docs: document Stack Auth deployment setup' clearly and concisely describes the main change in the PR: adding documentation for Stack Auth deployment configuration.
Description check ✅ Passed The description is directly related to the changeset, detailing the addition of AUTH_ARCHITECTURE.md, updates to DEPLOYMENT.md with Stack Auth configuration, and troubleshooting additions.
Linked Issues check ✅ Passed The PR addresses key coding-related requirements from issue #14: documenting Stack Auth architecture, adding deployment configuration, Vercel integration cleanup steps, and troubleshooting for REDIRECT_URL_NOT_WHITELISTED and OAuth failures.
Out of Scope Changes check ✅ Passed All changes are within scope: documentation files only (AUTH_ARCHITECTURE.md and DEPLOYMENT.md updates) directly addressing issue #14 requirements without unrelated code modifications.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-14-auth-docs

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@paccloud paccloud marked this pull request as ready for review May 10, 2026 21:53
coderabbitai[bot]
coderabbitai Bot reviewed May 10, 2026
View reviewed changes

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
DEPLOYMENT.md (1)

109-112: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify preview env vars are required when validating OAuth on preview deployments.

Marking preview variables as merely optional can cause avoidable OAuth failures in preview. Recommend stating they are required if preview auth testing is part of verification.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@DEPLOYMENT.md` around lines 109 - 112, Update the third step that currently
says "Optionally add for 'Preview' environments too" to clarify that preview
environment variables must be added when you need to validate OAuth on preview
deployments; specifically change the text to indicate: Add each variable for the
"Preview" environment as well when you plan to test or validate OAuth on preview
deployments (required for preview auth testing), and include a short note to
ensure preview-specific OAuth redirect URIs/credentials match the preview
deployment.
🤖 Prompt for all review comments with AI agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@DEPLOYMENT.md`:
- Around line 109-112: Update the third step that currently says "Optionally add
for 'Preview' environments too" to clarify that preview environment variables
must be added when you need to validate OAuth on preview deployments;
specifically change the text to indicate: Add each variable for the "Preview"
environment as well when you plan to test or validate OAuth on preview
deployments (required for preview auth testing), and include a short note to
ensure preview-specific OAuth redirect URIs/credentials match the preview
deployment.
ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cb329583-961e-4e0a-93a7-b4f9a9c5e8c3

📥 Commits

Reviewing files that changed from the base of the PR and between 6fe2dbf and 0adcfe5.

📒 Files selected for processing (2)
  • AUTH_ARCHITECTURE.md
  • DEPLOYMENT.md

@paccloud paccloud merged commit f8b05a6 into main May 10, 2026
5 checks passed
@paccloud paccloud deleted the issue-14-auth-docs branch May 10, 2026 21:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

fix: Stack Auth redirect URL not whitelisted — auth integration audit needed

1 participant

@paccloud